/*
 * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.nio.channels;

import java.io.IOException;
import java.nio.ByteBuffer;


/**
 * 可以读取字节的通道。
 *
 * <p> 在任何给定的时间内，可读通道上只能进行一个读操作。
 * 如果一个线程在一个通道上启动一个读操作，
 * 那么任何其他尝试启动另一个读操作的线程都会阻塞，直到第一个操作完成。
 * 其他类型的I/O操作是否可以与读取操作同时进行取决于通道的类型。</p>
 *
 *
 * @author Mark Reinhold
 * @author JSR-51 Expert Group
 * @since 1.4
 */

public interface ReadableByteChannel extends Channel {

    /**
     * 从这个通道读取一个字节序列到给定的缓冲区。
     *
     * <p> 尝试从通道中读取r字节，其中r是在调用此方法时缓冲区中剩余的字节数，即dst.remaining()。
     *
     * <p> 假设读取一个长度为n的字节序列, 并且 0 < = n < = r。
     * 字节序列将被转移到缓冲区,序列中的第一个字节对应缓冲区的索引为p，
     * 最后一个字节是指数p + n - 1, p是方法调用时，缓冲区的位置。
     * 返回后，缓冲区的位置将等于p + n;它的极限不会改变。
     *
     * <p> 读操作可能不会填充缓冲区，实际上它可能根本不会读取任何字节。
     * 它是否这样做取决于通道的性质和状态。
     * 一个套接字通道在非阻塞模式，例如，不能读取任何字节而不是立刻从套接字的输入缓冲区读取;
     * 类似地，文件通道只能读取文件中保留的字节。
     * 但是，可以保证的是，如果一个通道处于阻塞模式，并且缓冲区中至少有一个字节，
     * 那么这个方法将阻塞，直到至少一个字节被读取。
     *
     * <p> 此方法可以在任何时候调用。
     * 但是，如果另一个线程已经在这个通道上启动了读操作，那么对这个方法的调用将阻塞，直到第一个操作完成。</p>
     *
     * @param  dst
     *         The buffer into which bytes are to be transferred
     *
     * @return  The number of bytes read, possibly zero, or <tt>-1</tt> if the
     *          channel has reached end-of-stream
     *
     * @throws  NonReadableChannelException
     *          If this channel was not opened for reading
     *
     * @throws  ClosedChannelException
     *          If this channel is closed
     *
     * @throws  AsynchronousCloseException
     *          If another thread closes this channel
     *          while the read operation is in progress
     *
     * @throws  ClosedByInterruptException
     *          If another thread interrupts the current thread
     *          while the read operation is in progress, thereby
     *          closing the channel and setting the current thread's
     *          interrupt status
     *
     * @throws  IOException
     *          If some other I/O error occurs
     */
    public int read(ByteBuffer dst) throws IOException;

}
